The following is an overview of the API/Source for CALib. It is a compendium of discussions, OpenDoc™ documentation, developer experience and our current understandings.
The CALib API is modeled after the QuickTime APIs. The caller is required to check for it’s presence and avoid calling the API if it is not installed.
CALib API
Arbitration - CAArbitr.cpp
Description
This module contains routines used by the CA to deal with focus arbitration. The root frame of the specified window is the focus frame. If focus notification callbacks are registered, the proxy part calls through appropriately.
CALib defines the following focus types: kCAPrimaryFocus and kCAModalFocus.
CALib calls ExportClipboard() before calling the FocusAcquired() callback.
Must be called after closing any CA dialogs that require modal behavior.
Exceptions Handled:
kCAErrInvalidRequestor
Clipboard - CAClip.cpp
Description
CAGetClipboardDocument() acquires the clipboard focus for the caller and sets up the ODClipboard object to be used by the CA. The cloneKind is used to determine whether or not to clear the ODClipboard object. cloneKind may be kCACloneCopy, kCACloneCut or kCAClonePaste.
CACloseDocument() is called by the CA when the data transfer operation is complete.
The current CA clipboard implementation requires the CA to call CASetDocumentKind() to set the content value to the CA scrap type.
Related Recipes
Copying native content + embedded frames to the clipboard.
Copying a single embedded frame to the clipboard
Pasting native content + embedded frames from the clipboard.
Pasting a single embedded frame from the clipboard.
Embedding the contents of the clipboard as a part (same as above?)
Returns the reference to the OpenDoc Clipboard document.
Exceptions signaled:
none
Data Interchange - CADataX.cpp
The CADataX API provides the CA with the mechanism to clone frames (and their parts) to/from data transfer objects. The type of clone is determined from the cloneKind stored by the CADocument object representing the data transfer object. (E.g.. CAClipboardDocument, CADragDropDocument).
CACloneFrameRef() can handle the following clone contexts.
Clone between a CADocument and a data transfer document.
Clone from an OpenDoc CADocument (OD container file) to a CADocument.
The isRootFrameRef parameter to CACloneFrameRef indicates that either a single frame clone to a data transfer document, or a clone of the root part of a OpenDoc document to the CA document.
A CACloneKey is a pointer to a CACloneInfo object, which is used internally by CALib to manage a clone transaction.
Returns a CAFrameRef associated with the root frame of the specified document.
Exceptions signaled:
kCAErrInvalidDocument
Display - CADisplay.cpp
In order to make the frame contents visible, a call must be made to CAMakeVisFrame() which creates an OpenDoc facet that can be displayed by the CA. The facet is returned to the CA as a CAVisFrame (internally an ODFacet*). All display activities will be performed using this reference. The CAAdjustVisFrame() call is used to manipulate the visibility attributes associated with the facet such as display clipping and positioning within the presentation.
Manipulation of visFrame positioning is performed by manipulating the frame’s external transform. This is an opaque data type to the CA implementor. In order to facilitate manipulation of the transform data, two utility functions have been provided: CAMoveTransformBy, and CAMoveTransformTo. Other calls that would implement other transform manipulations may be implemented as required.
The CARemoveVisFrame() call removes the indicated facet from the frame. This serves to avoid redraw of parts not visible when scrolled off of the screen. This would be useful as a performance optimization only.
Note that this API only supports a single VisFrame (OpenDoc facet) per frame, as there is no way to distinguish between multiple facets.
Offscreen canvases work mostly transparently. If a CA wants an embedded part to image offscreen, it should provide the GWorld/viewport (or appropriate data type) to the MakeVisFrame call. Also, the CA must provide a callback for Part::UpdateCanvas so that OpenDoc can post notification that the part canvas has been updated.
CAs which want to do advanced imaging tricks like tinting, transparency, interleaving, etc. must force drawing of embedded parts using a CAForceUpdate call.
The container application must draw the border and handles for the embedded parts when the border is selected (i.e. the embedded part is being resized or moved).
Set the highlight state of the facet and notify its part via part::HighlightChanged()
Exceptions signaled:
none
pascal void CAMoveTransformBy (CATransform* transform, Point offset);
Shifts the transform by the amount indicated in offset. Utility function.
Exceptions signaled:
none
pascal void CAMoveTransformTo (CATransform* transform, Point origin);
Shifts the transform to the new origin. Utility function.
Exceptions signaled:
none
Drag and drop - CADnd.cpp
This module provides a Drag&Drop interface to the CA, which interacts appropriately with the ODDragAndDrop object. Internally, the CADnd implementation essentially duplicates much of the functionality implemented in DragDrp.cpp, with modifications to handle CALib specific issues.
CAStartDrag sets up the Macintosh Drag&Drop DragReference to include flavors written to the CADragDrop document by the CA and also other default flavors required by OpenDoc.
Note: The routines CARemoveTrackingHandler() and CARemoveReceiveHandler() were removed
To a CA, a CADocumentRef represents an OpenDoc data stream, which may be associated with a CA document, the OpenDoc clipboard, the OpenDoc Drag&Drop, or an OpenDoc part document.
CACreateDocument() is used by the CA to create new embedding units. CAOpenDocument() may be used to open previously saved CA CADocument’s or OpenDoc part documents.
For each open document, CALib internally maintains a working ODFileContainer. CASaveDocument() will either save the working file container, or copy a stream representation of the file container to the CA for later reconstitution.
CASetDocumentKind() and CAGetDocumentKind() are used to access the current value stream of the documents kCAPropContents property. CASetDocumentKind() sets the type of the first value in the kODPropContents property. The CALib Stream API can then be used to read/write data to/from the value stream.
Sets the routine to be called when an error is reported by OpenDoc.
Exceptions signaled:
kCAErrExistingErrorProc
kCAErrInvalidErrorProc
Inititialization - CAInit.cpp
Description
This module contains initialization routines for CALib CAInit() & CAShutdown() are called by the CA. CAInit() allocates and initializes a CASession object, CAShutdown() deletes the CASession object.
The CASession object maintains various data structures and state information relating to a single CALib session.
API
pascal void CAInit()
Initializes a CALib Session. Allocates and initializes an OpenDoc Session.
Exceptions signaled:
kCAErrOutOfMemory
pascal void CAShutdown()
This call must unregister any callbacks, menu commands, etc... that have been registered by the CA. This may require all CALib API’s to keep track of such modifications in a globally accessible list...
Allows CA to receive notification whenever a part’s representation has changed.
Exceptions signaled:
kCAErrInvalidHandler
pascal void CACanvasUpdated( GrafPtr port,
CAGraphicsSystem graphicSystem )
Default proc for notification when the part’s canvas has changed.
Exceptions signaled:
none
Layout - CALayout.cpp
The Layout API allows the CA control and access of embedded frame’s display area and internal transform. The frame shape and transform calls basically map directly to their ODFrame counterpart.
The internal transform of a frame represents the offset of the frame's content within the frame.
